.Dd September 20, 2025
.Dt R_EGG 3
.Os
.Sh NAME
.Nm r_egg
.Nd radare2 egg shellcode generation library
.Sh SYNOPSIS
.In r_egg.h
.Sh DESCRIPTION
The
.Nm r_egg
library provides shellcode generation capabilities for radare2, allowing users to write shellcode in a high-level language and compile it to machine code. It supports multiple architectures and provides a framework for creating, compiling, and executing shellcode.
.Pp
The core structure is
.Vt REgg ,
which manages source code, compiled binary, assembler, syscall information, and language parsing.
.Sh INITIALIZATION
.Pp
This section describes functions to create, initialize and free an REgg
context and contains helpers to (re)configure the embedded language parser and
state used during compilation.
.Ft REgg *
.Fn r_egg_new "void"
.Pp
Creates a new egg context with default settings.
.Pp
.Ft void
.Fn r_egg_free "REgg *egg"
.Pp
Frees all resources associated with the egg context.
Pp
.Ft void
.Fn r_egg_reset "REgg *egg"
.Pp
Resets the egg context state so it can be reused for a new compilation.
.Pp
.Ft char *
.Fn r_egg_tostring "REgg *egg"
.Pp
Returns a textual representation of the egg internal state (for debugging).
.Pp
.Ft void
.Fn r_egg_lang_init "REgg *egg"
.Pp
Initializes the embedded language parser state (`egg->lang`).
.Pp
.Ft void
.Fn r_egg_lang_free "REgg *egg"
.Pp
Frees resources allocated by the embedded language parser.
.Pp
.Ft bool
.Fn r_egg_setup "REgg *egg" "const char *arch" "int bits" "int endian" "const char *os"
.Pp
Configures the egg context for the specified architecture, bitness, endianness, and operating system.
.Sh LOADING CODE
.Pp
Functions to load egg source from strings or files, append fragments, and
manage include paths and ancillary source used during compilation.
.Ft void
.Fn r_egg_load "REgg *egg" "const char *code" "int format"
.Pp
Loads source code into the egg context. `format` indicates input style (egg/c).
.Pp
.Ft void
.Fn r_egg_append "REgg *egg" "const char *src"
.Pp
Appends additional source code to the egg context.
.Sh COMPILATION
.Pp
Compilation is generally a two-step process: parse/compile the egg language
into an intermediate representation, then assemble that IR into machine code.
This section lists helpers for both stages and utilities to obtain assembly
listings for inspection.
.Ft bool
.Fn r_egg_compile "REgg *egg"
.Pp
Compiles the loaded source code into intermediate representation.
.Pp
.Ft bool
.Fn r_egg_assemble "REgg *egg"
.Pp
Assembles the compiled code into machine code.
.Pp
.Ft bool
.Fn r_egg_assemble_asm "REgg *egg" "char **asm_list"
.Pp
Assembles the code and returns the assembly listing in `asm_list`.
.Sh EXECUTION
.Pp
Functions that run the generated shellcode either directly or via a ROP
execution helper; frontends use these to invoke or emulate the generated
payload.
.Ft int
.Fn r_egg_run "REgg *egg"
.Pp
Executes the compiled shellcode.
.Pp
.Ft int
.Fn r_egg_run_rop "REgg *egg"
.Pp
Executes the shellcode using ROP (Return-Oriented Programming) techniques.
.Sh OUTPUT
.Pp
Functions to access compilation results: the raw binary buffer, the original
source text, and the emitted assembly listing. These are commonly used by
frontends to print, save or further process the produced artifacts.
.Ft RBuffer *
.Fn r_egg_get_bin "REgg *egg"
.Pp
Returns the compiled binary code as a buffer.
.Pp
.Ft char *
.Fn r_egg_get_source "REgg *egg"
.Pp
Returns the source code.
.Pp
.Ft char *
.Fn r_egg_get_assembly "REgg *egg"
.Pp
Returns the assembly representation of the compiled code.
.Sh SYSCALLS
.Pp
Helpers to insert syscall invocations and to manage syscall-related language
state (argument marshaling, syscall table entries and emitted code).
.Ft void
.Fn r_egg_syscall "REgg *egg" "const char *arg" "..."
.Pp
Adds a syscall instruction to the shellcode.
.Sh MEMORY MANAGEMENT
.Pp
Functions to reserve and manipulate data used by generated code: allocate
space, place strings and manage small data patches emitted into the output
buffer.
.Ft void
.Fn r_egg_alloc "REgg *egg" "int n"
.Pp
Allocates memory in the shellcode.
.Sh CONTROL FLOW
.Pp
Labeling, branching and conditional helpers used by the egg language to
implement control flow constructs such as labels, if/while blocks and simple
arithmetic operations.
.Ft void
.Fn r_egg_label "REgg *egg" "const char *name"
.Pp
Defines a label in the shellcode.
.Pp
.Ft void
.Fn r_egg_if "REgg *egg" "const char *reg" "char cmp" "int v"
.Pp
Adds a conditional statement.
.Sh RAW CODE
.Pp
Low-level helpers to insert raw bytes or preassembled snippets directly into
the output buffer for cases where the high-level language cannot express a
pattern or when hand-crafted machine code is required.
.Ft bool
.Fn r_egg_raw "REgg *egg" "const ut8 *b" "int len"
.Pp
Inserts raw binary code into the shellcode.
.Sh ENCODING
.Pp
Encoder and shellcode-template helpers. Encoders transform the produced
binary (for obfuscation or packing) while shellcode templates provide
parameterizable payloads and generators that frontends may select.
.Ft bool
.Fn r_egg_encode "REgg *egg" "const char *name"
.Pp
Applies an encoder to the shellcode.
.Pp
.Ft bool
.Fn r_egg_shellcode "REgg *egg" "const char *name"
.Pp
Generates shellcode using a specific shellcode template.
.Sh PATCHING
.Pp
Binary patching helpers to apply small modifications to the compiled output
(bytes, words, qwords). The CLI uses these to apply user-specified patches
before finalizing output.
.Ft bool
.Fn r_egg_patch "REgg *egg" "int off" "const ut8 *b" "int l"
.Pp
Patches the compiled binary at the specified offset. Use `-1` for append.
.Sh PLUGINS
.Pp
The plugin framework used to extend r_egg with shellcode generators and
encoders. Hosts discover and register plugin implementations which are then
invoked during compilation or encoding phases.
.Ft bool
.Fn r_egg_plugin_add "REgg *a" "REggPlugin *plugin"
.Pp
Adds an egg plugin (encoder or shellcode generator).
.Pp
.Ft bool
.Fn r_egg_plugin_remove "REgg *a" "REggPlugin *plugin"
.Pp
Removes an egg plugin.
.Sh OPTIONS
.Pp
Key/value configuration used to control compilation and encoding behavior
(selected encoder, padding, chosen shellcode template and auxiliary keys used
by plugins).
.Ft void
.Fn r_egg_option_set "REgg *egg" "const char *k" "const char *v"
.Pp
Sets an option for the egg context.
.Pp
.Ft char *
.Fn r_egg_option_get "REgg *egg" "const char *k"
.Pp
Gets an option value from the egg context.
.Sh INCLUDES
.Pp
Include helpers to load files or strings (for example C headers or inline
code) referenced by egg source. Also contains helpers to manage include
search paths used by the preprocessor.
.Ft bool
.Fn r_egg_include "REgg *egg" "const char *file" "int format"
.Pp
Includes a file in the egg compilation.
.Pp
.Ft bool
.Fn r_egg_include_str "REgg *egg" "const char *arg"
.Pp
Includes a string in the egg compilation.
.Pp
.Ft void
.Fn r_egg_lang_include_path "REgg *egg" "const char *path"
.Pp
Adds an include path used by the egg preprocessor.
.Pp
.Ft void
.Fn r_egg_lang_include_init "REgg *egg"
.Pp
Initializes include-related state (called at setup time by hosts).
.Sh FINALIZATION
.Pp
Finalizers and convenience helpers called after compilation to finish
transformations, apply padding/encoders and release temporary resources.
.Ft void
.Fn r_egg_finalize "REgg *egg"
.Pp
Finalizes the egg compilation process.
.Pp
.Ft void
.Fn r_egg_printf "REgg *egg" "const char *fmt" "..."
.Pp
Printf-style helper to append formatted text to the current egg output (used
by emitters/plugins during code generation).
.Pp
.Ft void
.Fn r_egg_option_set "REgg *egg" "const char *k" "const char *v"
.Pp
Helper noted above; kept here to emphasize lifecycle usage by frontends.
.Sh EXAMPLES
Basic shellcode generation:
.Bd -literal -offset indent
REgg *egg = r_egg_new();
r_egg_setup(egg, "x86", 32, 0, "linux");
r_egg_load(egg, "write(1, \"Hello\", 5); exit(0);", 0);
r_egg_compile(egg);
r_egg_assemble(egg);
RBuffer *bin = r_egg_get_bin(egg);
.Ed
.Pp
Using syscalls:
.Bd -literal -offset indent
r_egg_syscall(egg, "exit", 0);
.Ed
.Pp
Adding raw code:
.Bd -literal -offset indent
ut8 code[] = {0x90, 0x90}; // NOP NOP
r_egg_raw(egg, code, 2);
.Ed
.Sh SEE ALSO
.Xr r_asm 3 ,
.Xr r_syscall 3
